Configuration API

Catalyst reads runtime and build configuration from config/config.json. This page covers the contract that the framework expects. For a guided walkthrough, see Configuration.

Top-Level Configuration

These keys are part of the core web runtime:

Key	Type	Required	Purpose
`NODE_SERVER_HOSTNAME`	`string`	Yes	Hostname for the Node SSR server
`NODE_SERVER_PORT`	`number`	Yes	Port for the Node SSR server
`WEBPACK_DEV_SERVER_HOSTNAME`	`string`	Yes	Hostname for the webpack dev server
`WEBPACK_DEV_SERVER_PORT`	`number`	Yes	Port for the webpack dev server
`BUILD_OUTPUT_PATH`	`string`	Yes	Output directory for production assets
`PUBLIC_STATIC_ASSET_PATH`	`string`	Yes	Public mount path for static assets
`PUBLIC_STATIC_ASSET_URL`	`string`	Yes	Base URL for emitted static assets
`CLIENT_ENV_VARIABLES`	`string[]`	Yes	Variables that should be exposed to the client bundle
`ANALYZE_BUNDLE`	`boolean`	Yes	Enables bundle analysis output

Application-specific values such as API_URL can also live in this file. They are available on the server through process.env.

Client-Exposed Environment Variables

Catalyst does not expose every config key to browser code automatically. Add the keys you want available on the client to CLIENT_ENV_VARIABLES.

{
  "API_URL": "https://api.example.com",
  "ANALYTICS_ID": "UA-123456",
  "DATABASE_URL": "postgresql://internal-db",
  "CLIENT_ENV_VARIABLES": ["API_URL", "ANALYTICS_ID"]
}

In this example:

process.env.API_URL is available on both server and client.
process.env.ANALYTICS_ID is available on both server and client.
process.env.DATABASE_URL stays server-only.

Keep this list small. Any key included here becomes visible in the client bundle.

`WEBVIEW_CONFIG`

Universal app settings live under WEBVIEW_CONFIG inside the same file.

config/config.json

{
  "WEBVIEW_CONFIG": {
    "port": "3005",
    "LOCAL_IP": "192.168.XX.XX",
    "appInfo": "android-5Feb2026-v2.1.0",
    "useHttps": false,
    "profiler": {
      "enabled": false
    },
    "android": {
      "appName": "My App",
      "packageName": "com.example.myapp",
      "buildType": "debug",
      "sdkPath": "/Users/yourname/Library/Android/sdk",
      "emulatorName": "Pixel_5_API_30"
    },
    "ios": {
      "appName": "My App",
      "appBundleId": "com.example.myapp",
      "buildType": "Debug",
      "simulatorName": "iPhone 17 Pro"
    },
    "accessControl": {
      "enabled": true,
      "allowedUrls": [
        "*.yourdomain.com*",
        "http://localhost:*"
      ]
    },
    "splashScreen": {
      "duration": 2000,
      "backgroundColor": "#ffffff",
      "imageWidth": 400,
      "imageHeight": 200,
      "cornerRadius": 20
    }
  }
}

Required Universal App Fields

Shared fields

Key	Required	Notes
`WEBVIEW_CONFIG.port`	Yes	Port the native WebView should load
`WEBVIEW_CONFIG.LOCAL_IP`	Yes	Use your LAN IP, not `localhost`
`WEBVIEW_CONFIG.appInfo`	Yes	Build identifier used by native tooling
`WEBVIEW_CONFIG.useHttps`	No	Defaults to `false`
`WEBVIEW_CONFIG.profiler.enabled`	No	Enables the debug-only Catalyst Profiler; defaults to `false`

Android fields

Key	Required	Notes
`WEBVIEW_CONFIG.android.sdkPath`	Yes	Absolute path to the Android SDK
`WEBVIEW_CONFIG.android.emulatorName`	Yes for debug	Required for emulator-based debug builds
`WEBVIEW_CONFIG.android.buildType`	No	`debug` or `release`
`WEBVIEW_CONFIG.android.keystoreConfig`	Yes for release	Needed to sign release output
`WEBVIEW_CONFIG.android.buildOptimisation`	No	Enables Android build optimisation

iOS fields

Key	Required	Notes
`WEBVIEW_CONFIG.ios.appBundleId`	Required for distribution	Set this explicitly for release builds
`WEBVIEW_CONFIG.ios.buildType`	No	Must be `Debug` or `Release`, case-sensitive
`WEBVIEW_CONFIG.ios.simulatorName`	No	Used for simulator builds
`WEBVIEW_CONFIG.ios.deviceUDID`	No	For physical device builds
`WEBVIEW_CONFIG.ios.developmentTeam`	Required with `deviceUDID`	Apple team ID for signing

Access Control

Use WEBVIEW_CONFIG.accessControl to whitelist outbound URLs used by the WebView and native request flows.

{
  "WEBVIEW_CONFIG": {
    "accessControl": {
      "enabled": true,
      "allowedUrls": [
        "*.yourdomain.com*",
        "https://api.example.com/*",
        "http://localhost:*"
      ]
    }
  }
}

If you enable access control, make sure every required API, CDN, and localhost URL is included.

Splash Screen

The splash screen configuration belongs inside WEBVIEW_CONFIG.splashScreen, not at the top level of config.json.

Key	Type	Notes
`backgroundColor`	`string`	Defaults to white
`duration`	`number`	Primarily relevant on iOS
`imageWidth`	`number`	Width of the splash asset
`imageHeight`	`number`	Height of the splash asset
`cornerRadius`	`number`	iOS rounded corners

Place splash assets at:

public/android/splashscreen.{png|jpg|jpeg|gif|bmp|webp}
public/ios/splashscreen.{png|jpg|jpeg}

Validation Notes

Missing required top-level config keys cause startup failures.
Using CLIENT_ENV_KEYS is outdated. The current key is CLIENT_ENV_VARIABLES.
iOS build types are case-sensitive: use Debug or Release.
LOCAL_IP should be a reachable LAN IP for emulator or device builds.